signifix
Number Formatter of Fixed Significance with Metric or Binary Prefix
Works now on stable Rust (>= 1.26.0)
Formats a given number in one of the three Signifix notations as defined below by determining
- the appropriate metric or binary prefix and
- the decimal mark position in such a way as to sustain a fixed number of four significant figures.
Contents
Signifix Notations
Three notations are defined,
- two with metric prefix, a default and an alternate, and
- one with binary prefix, a default only.
With Metric Prefix
The two Signifix notations with metric prefix comprise
- a signed significand of four significant figures normalized from
±1.000
to±999.9
to cover the three powers of ten of a particular metric prefix with the three different decimal mark positions between these four figures, and - a metric prefix symbol or its placeholder in case of no prefix
- either being appended along with a whitespace as in
±1.234␣k
, that is the default notation, - or replacing the decimal mark of the significand as in
±1k234
, that is the alternate notation.
- either being appended along with a whitespace as in
In default notation the placeholder is another whitespace as in ±1.234␣␣
to align consistently, while in alternate notation it is a number sign as in
±1#234
to conspicuously separate the integer from the fractional part of
the significand. The locale-sensitive decimal mark defaults to a decimal
point. The plus sign of positive numbers is optional.
With Binary Prefix
The one Signifix notation with binary prefix comprises
- a signed significand of four significant figures normalized from
±1.000
over±999.9
to±1 023
to cover the four powers of ten of a particular binary prefix with the three different decimal mark positions between these four figures and a thousands separator, and - a binary prefix symbol or its placeholder in case of no prefix being
appended along with a whitespace as in
±1.234␣Ki
.
To align consistently, the placeholder is another two whitespaces as in
±1.234␣␣␣
. The locale-sensitive decimal mark defaults to a decimal point
while the locale-sensitive thousands separator defaults to a whitespace as
in ±1␣023␣Ki
. The plus sign of positive numbers is optional.
Usage
This crate is on crates.io and can be
used by adding signifix
to the dependencies in your project's
Cargo.toml
:
[]
= "0.9"
# Optionally enable `try_from` support on nightly Rust.
#[dependencies.signifix]
#features = ["nightly"]
and this to your crate root:
// Optionally enable `try_from` support on nightly Rust.
// Required if the `nightly` feature is enabled in your `Cargo.toml`.
//#![feature(try_from)]
extern crate signifix;
Examples
The Notations
The Signifix notations result in a fixed number of characters preventing jumps to the left or right while making maximum use of their occupied space:
use TryFrom; // Until stabilized.
use ;
let metric = ;
let binary = ;
// Three different decimal mark positions covering the three powers of ten
// of a particular metric prefix.
assert_eq!; // 3rd
assert_eq!; // 1st
assert_eq!; // 2nd
assert_eq!; // 3rd
assert_eq!; // 1st
assert_eq!; // 2nd
assert_eq!; // 3rd
assert_eq!; // 1st
assert_eq!; // 2nd
assert_eq!; // 3rd
assert_eq!; // 1st
// Three different decimal mark positions and a thousands separator covering
// the four powers of ten of a particular binary prefix.
assert_eq!; // 1st
assert_eq!; // 2nd
assert_eq!; // 3rd
assert_eq!; // 4th
assert_eq!; // 1st
assert_eq!; // 2nd
assert_eq!; // 3rd
assert_eq!; // 4th
assert_eq!; // 1st
// Rounding over prefixes is safe against floating-point inaccuracies.
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
Transfer Rate
This is useful to smoothly refresh a transfer rate within a terminal:
use TryFrom; // Until stabilized.
use f64;
use Duration;
use ;
let transfer_rate = ;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
Measured Amps
Or to monitor a measured quantity like an electrical current including its direction with positive numbers being padded to align with negative ones:
use TryFrom; // Until stabilized.
use ;
let measured_amps = ;
assert_eq!;
assert_eq!;
assert_eq!;
Filesize Diff
While to visualize a change in file size, a plus sign might be preferred for positive numbers:
use TryFrom; // Until stabilized.
use ;
let filesize_diff = ;
assert_eq!;
assert_eq!;
assert_eq!;
Boundary Stat
The binary prefix instead suits well to visualize quantities being multiples of powers of two, such as memory boundaries due to binary addressing:
use TryFrom; // Until stabilized.
use ;
let boundary_stat = ;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
Localizations
Until there is a recommended and possibly implicit localization system for
Rust, explicit localization can be achieved by wrapping the Signifix
type
into a locale-sensitive newtype which implements the Display
trait via the
Signifix::fmt()
method:
use TryFrom; // Until stabilized.
use ;
; // English SI style (default)
; // English locale (whitespace -> comma)
; // German locale (comma <-> point)
let localizations = ;
assert_eq!;
assert_eq!;
Customization
Customization can be achieved by extracting information from the Signifix
type via its methods:
use TryFrom; // Until stabilized.
use ;
;
let customization = ;
assert_eq!;
License
Copyright (c) 2016, 2017 Rouven Spreckels n3vu0r@qu1x.org
Usage of the works is permitted provided that this instrument is retained with the works, so that any entity that uses the works is notified of this instrument.
DISCLAIMER: THE WORKS ARE WITHOUT WARRANTY.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the works by you shall be licensed as above, without any additional terms or conditions.